//+------------------------------------------------------------------+
//|                       ArrayColor.mqh 颜色数组类头文件           |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include "Array.h"  // 引入基础数组类头文件，CArrayColor 继承自 CArray
//+------------------------------------------------------------------+
//| CArrayColor 类                                                   |
//| 功能：用于管理 color 类型（颜色值）的动态数组类                 |
//| 继承关系：派生自基础数组类 CArray                                |
//+------------------------------------------------------------------+
class CArrayColor : public CArray
  {
protected:
   color             m_data[];           // 存储颜色数据的数组（核心数据容器）

public:
   /**
    * @brief 构造函数：初始化 CArrayColor 类实例
    * @details 初始化受保护的数组相关成员变量，为颜色数据存储做准备
    */
                     CArrayColor(void);

   /**
    * @brief 析构函数：销毁 CArrayColor 类实例
    * @details 释放数组占用的内存资源，避免内存泄漏
    */
                    ~CArrayColor(void);

   //--- 对象类型识别方法
   /**
    * @brief 获取当前数组对象的类型标识
    * @return int - 类型标识，固定返回 TYPE_COLOR（表示颜色类型数组）
    */
   virtual int       Type(void) const { return(TYPE_COLOR); }

   //--- 文件操作相关方法
   /**
    * @brief 将数组数据写入文件
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 获得）
    * @return bool - 操作结果：true 表示写入成功，false 表示写入失败
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件读取数据到数组
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 获得）
    * @return bool - 操作结果：true 表示读取成功，false 表示读取失败
    */
   virtual bool      Load(const int file_handle);

   //--- 动态内存管理方法
   /**
    * @brief 为数组预留指定大小的内存空间
    * @details 检查当前空闲空间是否满足需求，不足时按步长扩容，避免频繁内存分配
    * @param size [in] 需要预留的空闲元素数量
    * @return bool - 操作结果：true 表示预留成功，false 表示预留失败（如参数无效）
    */
   bool              Reserve(const int size);

   /**
    * @brief 调整数组大小（超出部分元素会被截断删除）
    * @param size [in] 调整后的数组元素总容量（不是空闲空间）
    * @return bool - 操作结果：true 表示调整成功，false 表示调整失败（如参数无效）
    */
   bool              Resize(const int size);

   /**
    * @brief 彻底清空数组并释放所有内存
    * @details 重置数组数据、容量、长度等所有成员变量，释放占用的内存
    * @return bool - 操作结果：true 表示清理成功，false 表示清理失败
    */
   bool              Shutdown(void);

   //--- 数组填充相关方法
   /**
    * @brief 向数组末尾添加一个颜色元素
    * @param element [in] 要添加的 color 类型元素（颜色值）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败（如内存不足）
    */
   bool              Add(const color element);

   /**
    * @brief 将外部 color 数组的所有元素添加到当前数组末尾
    * @param src [in] 外部 color 类型数组（需传入数组引用）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败
    */
   bool              AddArray(const color &src[]);

   /**
    * @brief 将另一个 CArrayColor 实例的所有元素添加到当前数组末尾
    * @param src [in] 指向另一个 CArrayColor 实例的指针（需确保指针有效）
    * @return bool - 操作结果：true 表示添加成功，false 表示添加失败（如指针无效）
    */
   bool              AddArray(const CArrayColor *src);

   /**
    * @brief 在数组指定位置插入一个颜色元素
    * @details 插入位置后的元素会自动后移，数组长度加 1
    * @param element [in] 要插入的 color 类型元素
    * @param pos [in] 插入位置的索引（从 0 开始）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如位置无效）
    */
   bool              Insert(const color element,const int pos);

   /**
    * @brief 将外部 color 数组的所有元素插入到当前数组指定位置
    * @details 插入位置后的元素会自动后移，数组长度增加外部数组的元素个数
    * @param src [in] 外部 color 类型数组（需传入数组引用）
    * @param pos [in] 插入位置的索引（从 0 开始）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败
    */
   bool              InsertArray(const color &src[],const int pos);

   /**
    * @brief 将另一个 CArrayColor 实例的所有元素插入到当前数组指定位置
    * @details 插入位置后的元素会自动后移，数组长度增加源实例的元素个数
    * @param src [in] 指向另一个 CArrayColor 实例的指针（需确保指针有效）
    * @param pos [in] 插入位置的索引（从 0 开始）
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如指针无效）
    */
   bool              InsertArray(const CArrayColor *src,const int pos);

   /**
    * @brief 用外部 color 数组的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组，再将外部数组的所有元素复制到当前数组
    * @param src [in] 外部 color 类型数组（需传入数组引用）
    * @return bool - 操作结果：true 表示赋值成功，false 表示赋值失败
    */
   bool              AssignArray(const color &src[]);

   /**
    * @brief 用另一个 CArrayColor 实例的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组，再将源实例的所有元素复制到当前数组
    * @param src [in] 指向另一个 CArrayColor 实例的指针（需确保指针有效）
    * @return bool - 操作结果：true 表示赋值成功，false 表示赋值失败（如指针无效）
    */
   bool              AssignArray(const CArrayColor *src);

   //--- 数组元素访问方法
   /**
    * @brief 获取数组指定索引位置的颜色元素
    * @param index [in] 要访问的元素索引（从 0 开始，需在有效范围内）
    * @return color - 对应索引的颜色元素；若索引无效，返回 clrNONE（无颜色值）
    */
   color             At(const int index) const;

   /**
    * @brief 重载 [] 运算符，通过索引直接访问数组元素（等价于 At 方法）
    * @param index [in] 要访问的元素索引（从 0 开始，需在有效范围内）
    * @return color - 对应索引的颜色元素；若索引无效，返回 clrNONE
    */
   color operator[](const int index) const { return(At(index)); }

   //--- 最小值/最大值查找方法
   /**
    * @brief 在数组指定范围内查找最小值的索引
    * @param start [in] 查找范围的起始索引（从 0 开始）
    * @param count [in] 查找的元素个数（需确保 start + count 不超出数组长度）
    * @return int - 最小值所在的索引；若范围无效，返回 -1
    */
   int               Minimum(const int start,const int count) const { return(CArray::Minimum(m_data,start,count)); }

   /**
    * @brief 在数组指定范围内查找最大值的索引
    * @param start [in] 查找范围的起始索引（从 0 开始）
    * @param count [in] 查找的元素个数（需确保 start + count 不超出数组长度）
    * @return int - 最大值所在的索引；若范围无效，返回 -1
    */
   int               Maximum(const int start,const int count) const { return(CArray::Maximum(m_data,start,count)); }

   //--- 数组元素修改方法
   /**
    * @brief 更新数组指定索引位置的颜色元素
    * @param index [in] 要更新的元素索引（需在有效范围内）
    * @param element [in] 新的 color 类型元素（用于覆盖原元素）
    * @return bool - 操作结果：true 表示更新成功，false 表示更新失败（如索引无效）
    */
   bool              Update(const int index,const color element);

   /**
    * @brief 将数组指定索引的元素按指定偏移量移动位置
    * @param index [in] 要移动的元素原始索引
    * @param shift [in] 偏移量（正数表示向后移动，负数表示向前移动）
    * @return bool - 操作结果：true 表示移动成功，false 表示移动失败（如位置越界）
    */
   bool              Shift(const int index,const int shift);

   //--- 数组元素删除方法
   /**
    * @brief 删除数组指定索引位置的元素
    * @details 删除后，后续元素会自动前移，数组长度减 1
    * @param index [in] 要删除的元素索引（需在有效范围内）
    * @return bool - 操作结果：true 表示删除成功，false 表示删除失败（如索引无效）
    */
   bool              Delete(const int index);

   /**
    * @brief 删除数组中指定范围的元素（从 from 到 to 的闭区间）
    * @details 删除后，后续元素会自动前移，数组长度减少（to - from + 1）
    * @param from [in] 删除范围的起始索引
    * @param to [in] 删除范围的结束索引（需满足 from ≤ to，且均在有效范围内）
    * @return bool - 操作结果：true 表示删除成功，false 表示删除失败（如范围无效）
    */
   bool              DeleteRange(int from,int to);

   //--- 数组比较方法
   /**
    * @brief 比较当前数组与外部 color 数组是否完全相等
    * @details 需元素个数、对应位置的颜色值均相同，才判定为相等
    * @param array [in] 要比较的外部 color 类型数组（需传入数组引用）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等
    */
   bool              CompareArray(const color &array[]) const;

   /**
    * @brief 比较当前数组与另一个 CArrayColor 实例是否完全相等
    * @details 需元素个数、对应位置的颜色值均相同，才判定为相等
    * @param array [in] 指向要比较的 CArrayColor 实例的指针（需确保指针有效）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等（如指针无效）
    */
   bool              CompareArray(const CArrayColor *array) const;

   //--- 有序数组操作方法（需数组已排序，否则方法无效）
   /**
    * @brief 向有序数组中插入元素（保持数组有序性）
    * @param element [in] 要插入的 color 类型元素
    * @return bool - 操作结果：true 表示插入成功，false 表示插入失败（如数组未排序）
    */
   bool              InsertSort(const color element);

   /**
    * @brief 在有序数组中查找指定颜色元素的索引
    * @param element [in] 要查找的 color 类型元素
    * @return int - 查找结果：找到时返回元素索引，未找到或数组未排序返回 -1
    */
   int               Search(const color element) const;

   /**
    * @brief 在有序数组中查找第一个大于指定元素的索引
    * @param element [in] 参考的 color 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchGreat(const color element) const;

   /**
    * @brief 在有序数组中查找第一个小于指定元素的索引
    * @param element [in] 参考的 color 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchLess(const color element) const;

   /**
    * @brief 在有序数组中查找第一个大于或等于指定元素的索引
    * @param element [in] 参考的 color 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchGreatOrEqual(const color element) const;

   /**
    * @brief 在有序数组中查找第一个小于或等于指定元素的索引
    * @param element [in] 参考的 color 类型元素
    * @return int - 查找结果：找到时返回对应索引，未找到或数组未排序返回 -1
    */
   int               SearchLessOrEqual(const color element) const;

   /**
    * @brief 在有序数组中查找指定元素第一次出现的索引
    * @param element [in] 要查找的 color 类型元素（可能存在多个相同值）
    * @return int - 查找结果：找到时返回第一次出现的索引，未找到或数组未排序返回 -1
    */
   int               SearchFirst(const color element) const;

   /**
    * @brief 在有序数组中查找指定元素最后一次出现的索引
    * @param element [in] 要查找的 color 类型元素（可能存在多个相同值）
    * @return int - 查找结果：找到时返回最后一次出现的索引，未找到或数组未排序返回 -1
    */
   int               SearchLast(const color element) const;

   /**
    * @brief 对数组进行线性查找（遍历数组，适用于无序数组）
    * @param element [in] 要查找的 color 类型元素
    * @return int - 查找结果：找到时返回第一个匹配元素的索引，未找到返回 -1
    */
   int               SearchLinear(const color element) const;

protected:
   /**
    * @brief 快速排序算法：对数组指定范围元素进行排序（内部使用）
    * @param beg [in] 排序范围的起始索引
    * @param end [in] 排序范围的结束索引
    * @param mode [in] 排序模式（默认 0，通常表示升序，具体取决于父类定义）
    */
   virtual void      QuickSort(int beg,int end,const int mode=0);

   /**
    * @brief 快速查找算法：在有序数组中定位元素位置（内部使用，为 Search 系列方法提供支持）
    * @param element [in] 要查找的 color 类型元素
    * @return int - 查找的中间位置索引（不一定是匹配元素，需进一步判断）
    */
   int               QuickSearch(const color element) const;

   /**
    * @brief 数组内部内存移动：将指定范围元素从源位置复制到目标位置（内部使用）
    * @param dest [in] 目标位置的起始索引
    * @param src [in] 源位置的起始索引
    * @param count [in] 要移动的元素个数
    * @return int - 操作结果：成功返回目标位置起始索引，失败返回 -1
    */
   int               MemMove(const int dest,const int src,int count);
  };
//+------------------------------------------------------------------+